Milestone 3 provided us with plentiful of valuable criticism which we turned into an actionable revision plan. Our review plan further includes how we plan on processing feedback from Milestone 1 and 2.
Our colleagues have communicated with us the ways in which our AD fails to properly inform the readers. Our mission is to showcase that Gradle meets its functional and non-functional requirements. The functional requirements emphasized in our AD are partially detailed in the important scenarios section.
This document highlights the important feedback and the actions taken to address the criticism. We also provide justifications for our actions which should prove to be insightful to readers. The justifications will detail our reasoning behind the actions taken, such as the tradeoffs we had to consider, etc...
What’s the difference between “Dependency Repository” and “Repository”?
Completely address
We were too specific in our initial context view. We wanted to differentiate between the repositories which contain plugins and which contain source code dependencies. However, we now recognize that the distrinction is not necessary, especially not within in the context view.
We will merge the two terms into a singular external element called “Repository”.
Varying fonts and small label margins make the diagram harder to read and "crowded"
Completely address
In retrospect, we recognize that the varying font sizes clutter the diagram. We used varying font sizes to highlight elements of varying importance, however we believe that readibility is more important.
We will pick a uniform font size for our models (except for the main element: Gradle).
View lacks depth and refinement: the information is hard to parse for a reader unfamiliar with the system, and entities should be described more thoroughly
Completely address
Gradle is an extremely complex system, we initially dove too deep in the code and drew a blurry line between software implementation and software architecture. We believe that a healthy level of abstraction should be present in our views.
We will add a glossary of terms and abstract some of the more unclear aspects of Gradle. We will put useful, yet unecessary detail into an appendix.
Some groups of stakeholders can have varying power/interest
Partially address
We think that most stakeholders have similar power/interest, we do agree that some stakeholders (notably project developers) should have varying power/interest.
We will modify the power/interest of some stakeholders in our stakeholder such that the "range" of power/interest is more detailed.
Stakeholders somewhat user- and developer-focused
Ignore
Gradle as a software is very much a user- and developer-focused tool. Users/Developers are our highest priority stakeholders Therefore, we believe that the focus on our highest priority stakeholders is appropriate.
N/A
Why do Android developers have higher power than other project developers or development tool developers?
Partially address
We added this as we felt that their connection with Google and their ecosystem made Android developers more important. However, we now see how specifying Android Developers leads to confusion. Especially since we do not specify Google as a stakeholder.
We will remove Android Developers since they belong to Project Developers.
List of stakeholders could be better sorted
Completely address
We agree that a sorting the list of stakeholders by priority is good and does not have any downside (compared to our current arrangement).
The stakeholders will be sorted in descending order by priority (highest priority on top). Priority is subjectively derived from the power/interest metric.
No architectural style or pattern
Completely address
We completely forgot to mention architectural styles and software design patterns.
We will add information in the appendix relating to the microkernel architeral style Gradle is based on, we will also add an entry comparing Tasks to the command design pattern. We will reference the appendix from the appropriate views.
There is something off-putting about Task providing an executeTask() interface. A Task sounds like a form of Command pattern; is there some sort of Processor somewhere to execute it?
Partially address
Tasks can be seen as containers for Actions, actions themselves can be executed. We believe that the ExecuterSystem currently is currently too abstract which might be the cause of the confusion.
We will address this when we rewrite our functional view. We believe our current functional view is lacking and confusing. Our new view should clearly distinguish between the initialization system and the execution system (responsible for executing tasks).
It is also a little confusing to have object names for interfaces(e.g., ActionBuilder.) If the object is not important enough to be a component, perhaps it should be abstracted as a function (e.g., "buildAction")? If it is important, perhaps it can be modeled as a connector?
Completely address
The criticism is correct in that the way we named interfaces added unnecessary complexity. We tried to be too specific in our original views, we believe that we should allow abstractions and put less emphasis on the Gradle's current software implementation.
Interfaces will be renamed and absracted using "method names". We will also reorganize the views to be more readable.
There is an inconsistency in the notation of the interfaces, with the “()” at the end of some interfaces being used to reference an actual method in the code. This is never explained in the view. I would either include a definition in the diagram (i.e., through a legend) or remove the “()” and reference the method (including the class/code line it comes from) in the element catalogue description of the interface.
Completely address
We ignored the implications of using parenthesis ("method calls") in only some of our interfaces, we agree that this can be misleading and confusing.
We will ensure that our interface names are consistent when rewriting our views.
The main(args) provided interface is not in the element catalogue. I am not sure what this interface does, or who uses it?
Ignore
Since our AD focuses on the developer stakeholders, we believe that main(args) is commonly used to denote a program's entry point. We will not address this, we believe the use of main(args) is appropriate and not misleading.
N/A
What is the role of the Daemon Server? I am unsure if the Daemon Server is an external element? When discussing the DaemonClient element you mention that it sends messages to the server, but there is no interface provided by the client to access the server nor an external element present in the diagram.
Completely address
The daemon is used to ensure Gradle meets its performance quality property. We believe our current explanations are insuffcient for such a crucial architectural element.
when applying the Performance perspective on our views, more notably the functional view, we will make sure to better detail the Daemon.
The subsystem of plugins seems incomplete. For example, in the element catalogue, you say “The JavaPlugin applies the BasePlugin” which seems as though there should be an interface linking JavaPlugin and BasePlugin or two distinct interfaces provided to the project aside from the provided PluginManager. Specifically, the PluginManager does not appear to accommodate this behaviour, as it only keeps track of plugins applied. Overall, more clarity is needed on the interactions between plugins.
Completely address
We attempted to give example of plugins (BasePlugin, JavaPlugin, ...) by showing plugin as a subsytem in our functional view. We recognize that this is confusing since it not an appropriate way to model things.
The plugin interface will be renamed to be more explicit in the functionality a Plugin provides to the Project. We will model Plugin as a component rather than a subsytem, therefore we will remove the examples/implementations from our diagram.
In the element catalogue, specifically in the ExecuterSystem, you mention something called a context. It is brought up at other times, and it is mentioned in the sequence diagram. However, I do not understand what a context is, a clearer definition needs to be provided.
The ExecuterSystem was originally used to combine the initialization step of Gradle's build lifecycle and the execution step. In retrospect, we recognize that this is very confusing and unecessary. The "context" is not architecturally significant. We were simply answering our critics questions relating to Gradle's software implementation.
We will split the ExecuterSystem in two, the part responsible for the initialization of Gradle (Initializer) and the part responsible for the execution of tasks (Execution subsystem).
We will also model the components responsible for Gradle's initialization, configuration and execution in seperate models as subsystems. This will allow for clearer and more concise views.
We do not believe that detailing the components belonging to the execution subsystem is important (such as the TaskTree or ActionExecutor). Therefore we will provide an explanation of the execution system's responsibilities without detailing its inner workings.
In the discussion, you mention plugin component will add tasks to the task component. However, there is no interface provided to perform this process.
Partially address
The project does not add tasks to the Task component. It adds tasks to the project.
Renaming the interface between Plugin and Project will hopefully clarify this.
In the Component Diagram, both ActionManager and Daemon used BuildActionExecutor interface provided by ExecuterSystem. In the discussion, you mention Daemon is a safe way to execute the thread. However, this is not included in the element catalogue.
Completely address
We recognize that we did not properly detail the Daemon in our AD.
We will better detail the Daemon in our functional view's element catalogue.
Skips over potentially relevant details, e.g., Ivy (add reference?)
Partially address
We feel that going into deeper detail about the types of artifacts accepted is not relevant to the architecture of our system so we opt to just remove references to the types of accepted artifacts.
We will modify our context view by encapsulating all types of repositories under "Source".
There is no justification for why this sequence diagram is included in the functional view. What does it add to the view? What does it enlighten about the system? Why did you choose to show this sequence diagram and not others? It is important to tie back to a defined scope (functional capabilities) to justify why you are limiting to this sequence diagram. Why not show different versions of building?
Completely address
We recognize that we did not properly explain why we chose our sequence diagram and that our choice was questionable.
We will add more insightful sequence diagram(s). We will reconsider whether the current diagram is still needed once we have reworked our functional view. We will remove it if it is not.
There are no callbacks in the sequence diagram. We recommend that callbacks should be included to describe where the method ends (or if any information is returned or not). If no callbacks are included, a short justification in the description of the diagram would help justify this decision and avoid any confusion.
Ignore
We will continue to model callbacks only when necessary. We believe our sequence diagram does not have to showcase "void" or architecturally insignifcant callbacks.
N/A
There are no clear links between the interfaces and the methods on the calls (arrows). Upon questioning, we determined that they are abstractions of a series of methods in the code, which are a part of the interface. It would be nice if this was clarified.
Partially address
We believe that this confusion comes from using Java-like interface names in the component diagram (e.g "PluginManager" but we use a "managePlugins()" method in the sequence diagram).
We believe that after reworking our component diagram, the method names will be clearer.
In the description of the sequence diagram, you mention that the sequence diagram is: “a build action on a Gradle Project”. At the start of the view, you refer to a “build task”. Are a build action and a build task the same thing? Clearer language/consistency would be appreciated. This also loops back into the definitions of Task & Action (see global points below.)
Completely address
We recognize that we did not differentiate between a Task, Build, and an Action. Since all three are "conceptually interconnected", we find the confusion reasonable.
We will include a glossary to define commonly used terms.
What triggers the start of the sequence diagram? In other words, who sends the launch(args) call? Is it a user or is it triggered by a system event?
Ignore
We believe that this is already shown in the context view (the developers use Gradle). We do not believe that showing that "IDE" or "CLI" can be the entry points is architecturally signifcant.
N/A
The Introduction of the Information view mentions Gradle being concerned with some source files. While we understood from the presentation that this notably includes the build.gradle file, there was initially some confusion as to which files were being referenced; this could be clarified in the AD.
Completely address
We recognize that our information view is confusing, the mapping between configuration objects and files should be clear and explicit.
We will rewrite the information view to describe Gradle's elements which relate to its configurability rather than presenting a nebulous view of all the information that Gradle processes.
View lacks introduction/orientation to understand what's going on
Completely address
We recognize our AD lacks refinement and organization.
We will completely reorganize our AD and add introductions, context and orientation where necessary.
Why is ArtifactRepository's cardinality one to many? This suggests that an External Source (which we understand is a library dependency such as Apache Commons Math) can be managed by multiple ArtifactRepository objects. Is this true?
Partially address
The metadata model was not insightful with regards to how Gradle meets its functional requirements or achieves its desired quality properties.
We will no longer be using a metadata model. This will no longer be an issue.
The nature of the association between PublishedArtifact and File, ie that the latter is a persistent representation of the former, could be specified; otherwise it might be interpreted as PublishedArtifact using data contained in File in some way.
Partially address
We will completely rewrite our information view to focus on Gradle's configuration. A PublishedArtifact is not a configuration object.
Published artifact will no longer be addressed in the view.
Somewhat related to the term Source code, but perhaps Task could be added to the diagram. It is not necessarily that obvious that Tasks are defined in the build.gradle (also, perhaps this association could be added in the dynamic info model.) (Also also, since tasks can alternatively be defined in plugins, perhaps it is worth adding Plugin to the model as well.)
Completely address
We recognize that our view overlooked the location and strucutre of the data defining task behavior.
We will write a new view that shows how tasks can be defined in the build.gradle file or applied added to a project via plugins.
This may be a problem on Gradle's side, but what's the point of making Services singletons if they are accessed via a ServiceRegistry? It may be worth checking whether Services are actually singletons.
Partially address
In restrospect, we believe that the ServiceRegistry is an insignificant implemenation detail.
The ServiceRegistry will be removed from the information view.
At face value, a Service sounds like a functionality provider, a black box that takes input and emits output; how does it contribute to an information view?
Partially address
In restrospect, we believe that the ServiceRegistry is an insignificant implemenation detail.
The ServiceRegistry will be removed from the information view.
What do Services do? We understand they may cover a wide range of functionality, but a few examples could be helpful.
Partially address
In restrospect, we believe that the ServiceRegistry is an insignificant implemenation detail.
The ServiceRegistry will be removed from the information view.
This may or may not be relevant, but perhaps fields could be added to some of the components? It may help communicate the data contained in, and purpose of, components like Task and Plugin.
Ignore
The information stored in these components are wrapped in many layers of abstractions and we believe that adding fields will either confuse the reader or give an incorrect understanding of what is contained in these components.
N/A
If the Base plugin is always loaded, perhaps the Plugin cardinality is incorrect. Task also appears to be missing a cardinality (to the external observer it is not obvious whether a PublishedArtifact can be associated with multiple Tasks.)
Ignore
The assumption that the Base plugin is always loaded is incorrect. We also scoped out PublishedArtifact from our views and thus the criticism is no longer applicable.
N/A
A glossary would be useful. Several terms caused confusion during the presentation and were sometimes employed inconsistently : <Source Code, Data/Metadata, Gradle build, Dependency, Tasks/Actions
Completely address
We recognize that some terms can be confusing especially when they are not used consistently throughout the AD
We will include a glossary which includes terms we believe are confusing. We will also review our AD to ensure that the meaning of terms are consistent throughout the AD.
Where does dependency management fit into all this? We understand that Gradle is more of a processing service and doesn't manage lots of data (as opposed to a database system), but from a high-level, user's POV, one important piece of data that Gradle does manage are library dependencies. While these are somewhat represented in the ArtifactRepository component, it's not clear how this component interacts with the others and how dependencies are woven into the project.
Ignore
We believe that detailed explanations regarding dependency management will be software implementation details rather than architecturally significant information. We will not be addressing this due to timeliness constraints of our AD.
N/A
The views do not contain any code references or supporting evidence (e.g., links to data generated by analysis tools). It would be useful if there was a tangible reference to the system, both for proof, and as a pointer for further investigation.
Completely address
We recognize the lack of evidence throughout our AD.
We will add evidence via hyperlinks throughout our AD.
This section does not follow the same formatting as the other sections.
We presented our context view during the oral presentation. After our presentation, we were asked why Gradle was shown as residing within a project in the context model.
Our answer had little to do with Gradle's desired functionality (to build), but rather its potential functional capabilities (it can be heavily edited to the point where it is no longer a build automation tool and basically software). We recognize that this is not relevant in our AD.
We will review our context model to clearly distinguish between a project (the functional component/configuration object) and the software. We will also showcase Gradle as a seperate element in the context model.
It is unclear how tasks and plugins are added to a project.
We will add an entry in the appendix showcasing how tasks are added to a project's configuration script file. We will also add a sequence diagram detailing how plugins are applied on a project.
We believe our information view lacks architectural significance.
We will completely rewrite the information view to be focused on configuration objects.
We believe Gradle's build lifecycle has been ignored in our old AD. The build lifecycle is key to Gradle's functionality.
We will rewrite our functional view such that it is centered around Gradle's build lifecycle.
The development view currently looks like an information dump rather than a view.
We will improve and reorganize the development view.
Back when we had a very poor understanding of Gradle, we came up with some concerns and architectural principles. We no longer believe they are good concerns and architectural principles.
We will find and write good concerns and architectural principles to standalone documents. We will show evidence for our architectural principles and we will make sure our concerns are addressed throughout the AD.